Avatar stack
Avatar stacks are the most common way of showing the online status of members in an application by displaying an avatar for each member. Events are emitted whenever a member enters or leaves a space, or updates their profile data. Additional information can also be provided, such as a profile picture and email address.
Subscribe to the space.members namespace in order to keep your avatar stack updated in realtime.
Event types
The following four event types are emitted by members:
| Event | Description |
|---|---|
enter | A new member has entered the space. The member has either entered explicitly by calling space.enter(), or has attempted to update their profile data before entering a space, which will instead emit an enter event. |
updateProfile | A member has updated their profile data by calling space.updateProfileData(). |
leave | A member has left the space. The member has either left explicitly by calling space.leave(), or has abruptly disconnected and not re-established a connection within 15 seconds. |
remove | A member has been removed from the members list after the offlineTimeout period has elapsed. This enables members to appear greyed out in the avatar stack to indicate that they recently left for the period of time between their leave and remove events. |
update | This event is emitted whenever any one of the above events is emitted. |
Subscribe to member events
Subscribe to members' online status and profile updates by registering a listener. Member events are emitted whenever a member enters or leaves the space, or updates their profile data. Use the subscribe() method on the members object of a space to receive updates.
It's also possible to subscribe to multiple event types with the same listener by using an array:
Or subscribe to all event types:
The following is an example payload of a member event. The lastEvent.name describes which event type a payload relates to.
The following are the properties of a member event payload:
| Property | Description | Type |
|---|---|---|
| clientId | The client identifier for the member. | String |
| connectionId | The unique identifier of the member's connection. | String |
| isConnected | Whether the member is connected to Ably or not. | Boolean |
| profileData | The optional profile data associated with the member. | Object |
| location | The current location of the member. Will be null for enter, leave, and remove events. | Object |
| lastEvent.name | The most recent event emitted by the member. | String |
| lastEvent.timestamp | The timestamp of the most recently emitted event. | Number |
Unsubscribe from member events
Unsubscribe from member events to remove previously registered listeners.
The following is an example of removing a listener for one member event type:
It's also possible to remove listeners for multiple member event types:
Or remove all listeners:
Retrieve members
Space membership can be retrieved in one-off calls. These are local calls and retrieve the membership retained in memory by the SDK. One-off calls to retrieve membership can be used for operations such as displaying a member's own profile data to them, or retrieving a list of all other members to use to update their profile data.
The following is an example of retrieving a member's own member object:
The following is an example payload returned by space.members.getSelf():
The following is an example of retrieving an array of member objects for all members other than the member themselves. Ths includes members that have recently left the space, but have not yet been removed.
The following is an example payload returned by space.members.getOthers():
The following is an example of retrieving an array of all member objects, including the member themselves. Ths includes members that have recently left the space, but have not yet been removed.
The following is an example payload returned by space.members.getAll():
Example usage
The following is an example of the steps involved in implementing an avatar stack.
Avatar stack foundations
The Spaces SDK is built upon existing Ably functionality available in Ably's Core SDKs. Understanding which core features are used to provide the abstractions in the Spaces SDK enables you to manage space state and build additional functionality into your application.
Avatar stacks build upon the functionality of the Ably Pub/Sub presence feature. Members are entered into the presence set when they enter the space.